Build Optimization and Transforms

**Referenced Files in This Document** - [.eleventy.js](file://.eleventy.js) - [package.json](file://package.json) - [src/feed.njk](file://src/feed.njk) - [src/_data/site.json](file://src/_data/site.json) - [src/index.njk](file://src/index.njk) - [src/news.njk](file://src/news.njk) - [src/cases.njk](file://src/cases.njk) - [README.md](file://README.md)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document explains Eleventy’s build optimization and transform systems for the project. It covers:

  • The transform pipeline, including HTML minification for production, Obsidian syntax processing for wiki links and callouts, and asset optimization
  • The RSS feed generation system and its integration with content collections
  • Conditional transforms that run only in production environments
  • The relationship between transforms and the final HTML output
  • Practical examples for adding new transforms, optimizing build performance, and debugging transform issues
  • Caching strategies and build-time optimizations

Project Structure

The project uses Eleventy’s configuration to define passthrough copies, watch targets, filters, collections, transforms, and output directory mapping. The RSS feed is generated via a dedicated template that consumes the “news” collection. The build script integrates Pagefind indexing after Eleventy completes.

graph TB
A[".eleventy.js<br/>Configures passthrough, watch, filters, collections, transforms"]
B["package.json<br/>Scripts and dependencies"]
C["src/feed.njk<br/>RSS Atom feed template"]
D["src/_data/site.json<br/>Site metadata"]
E["_site/<br/>Built output"]
A --> E
B --> A
C --> E
D --> C

Diagram sources

  • [.eleventy.js:267-283](file://.eleventy.js#L267-L283)
  • [package.json:5-12](file://package.json#L5-L12)
  • [src/feed.njk:1-27](file://src/feed.njk#L1-L27)
  • [src/_data/site.json:1-20](file://src/_data/site.json#L1-L20)

Section sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [package.json:1-32](file://package.json#L1-L32)

Core Components

  • Passthrough copy and watch targets: Ensures static assets and related directories are watched and copied to the output.
  • Filters: Provide reusable transformations for dates, slugs, truncation, and more.
  • Collections: Define curated content sets (news, cases, newsletters, team members, featured news, services, knowledge).
  • Transforms:
    • Obsidian syntax processing for wiki links and callouts
    • HTML minification in production
  • RSS feed: Atom XML generated from the “news” collection

Section sources

  • [.eleventy.js:6-22](file://.eleventy.js#L6-L22)
  • [.eleventy.js:46-165](file://.eleventy.js#L46-L165)
  • [.eleventy.js:169-211](file://.eleventy.js#L169-L211)
  • [.eleventy.js:216-261](file://.eleventy.js#L216-L261)
  • [src/feed.njk:1-27](file://src/feed.njk#L1-L27)

Architecture Overview

The transform pipeline runs after templates render but before files are written to disk. Production-specific transforms are gated by environment variables. RSS generation is decoupled from content rendering via a dedicated template that iterates over the “news” collection.

sequenceDiagram
participant T as "Eleventy Template"
participant O as "Obsidian Syntax Transform"
participant M as "HTML Minify Transform"
participant FS as "File System"
T->>O : Rendered HTML content
O-->>M : Post-processed HTML (wiki links, callouts)
M-->>FS : Write minified HTML to _site

Diagram sources

  • [.eleventy.js:216-261](file://.eleventy.js#L216-L261)

Detailed Component Analysis

Obsidian Syntax Transform

Purpose:

  • Converts Obsidian-style wiki links into HTML anchor tags
  • Converts Obsidian-style callouts into structured HTML divs with accessibility attributes

Behavior:

  • Runs only on HTML output files
  • Uses regex to match wiki link patterns and callout blocks
  • Generates semantic HTML with appropriate classes and roles
flowchart TD
Start(["Transform Entry"]) --> CheckExt["Check outputPath endsWith '.html'"]
CheckExt --> |No| ReturnOrig["Return original content"]
CheckExt --> |Yes| ReplaceWiki["Replace wiki links with anchors"]
ReplaceWiki --> ReplaceCallouts["Replace callout blocks with divs"]
ReplaceCallouts --> ReturnMod["Return modified content"]

Diagram sources

  • [.eleventy.js:216-239](file://.eleventy.js#L216-L239)

Section sources

  • [.eleventy.js:216-239](file://.eleventy.js#L216-L239)

HTML Minification Transform (Production)

Purpose:

  • Reduce payload size by removing whitespace, comments, and redundant attributes
  • Improve page load performance in production builds

Behavior:

  • Conditionally registered when NODE_ENV equals production
  • Applies aggressive minification options to HTML content
  • Skips non-HTML files
flowchart TD
Start(["Transform Entry"]) --> EnvCheck{"NODE_ENV == 'production'?"}
EnvCheck --> |No| ReturnOrig["Return original content"]
EnvCheck --> |Yes| ExtCheck["outputPath endsWith '.html'?"]
ExtCheck --> |No| ReturnOrig
ExtCheck --> |Yes| Minify["Minify HTML with configured options"]
Minify --> ReturnMin["Return minified content"]

Diagram sources

  • [.eleventy.js:241-261](file://.eleventy.js#L241-L261)

Section sources

  • [.eleventy.js:241-261](file://.eleventy.js#L241-L261)

RSS Feed Generation

Purpose:

  • Provide an Atom XML feed for the “news” collection
  • Integrate with site metadata and content ordering

Behavior:

  • Dedicated template with a permalink to feed.xml
  • Iterates over the “news” collection in reverse chronological order
  • Uses site metadata for title, subtitle, and author
  • Excludes itself from automatic collections
sequenceDiagram
participant C as "collections.news"
participant F as "src/feed.njk"
participant S as "src/_data/site.json"
participant FS as "_site/feed.xml"
C-->>F : Sorted news items
S-->>F : Site title, description, url
F-->>FS : Atom XML with entries

Diagram sources

  • [src/feed.njk:1-27](file://src/feed.njk#L1-L27)
  • [src/_data/site.json:1-20](file://src/_data/site.json#L1-L20)

Section sources

  • [src/feed.njk:1-27](file://src/feed.njk#L1-L27)
  • [src/_data/site.json:1-20](file://src/_data/site.json#L1-L20)

Content Collections

Purpose:

  • Provide organized access to content across the site
  • Enable templates to iterate over curated sets

Examples:

  • News, cases, newsletters, team members, featured news, services, knowledge

Integration:

  • Templates reference collections to render lists and paginated views
  • RSS feed consumes the “news” collection

Section sources

  • [.eleventy.js:169-211](file://.eleventy.js#L169-L211)
  • [src/index.njk:117-139](file://src/index.njk#L117-L139)
  • [src/news.njk:109-112](file://src/news.njk#L109-L112)
  • [src/cases.njk:30-36](file://src/cases.njk#L30-L36)

Asset Optimization

Current state:

  • Passthrough copy is configured for assets, admin, and redirect files
  • No explicit asset pipeline plugins are enabled in the configuration
  • Sharp is present as a dependency; it can be used for image processing if integrated

Recommendations:

  • Integrate an Eleventy image plugin or a dedicated transform to process images during build
  • Consider enabling compression for CSS/JS assets if not handled elsewhere
  • Use cache headers and long-lived fingerprints for static assets in production

Section sources

  • [.eleventy.js:6-14](file://.eleventy.js#L6-L14)
  • [package.json:14-21](file://package.json#L14-L21)

Dependency Analysis

  • Transform registration depends on environment variables and optional dependencies
  • RSS feed depends on the “news” collection and site metadata
  • Build scripts depend on Eleventy and Pagefind for search indexing
graph LR
P["package.json scripts"] --> E[".eleventy.js"]
E --> T1["obsidianSyntax transform"]
E --> T2["htmlmin transform (production)"]
E --> COL["collections (news, cases, etc.)"]
COL --> FEED["src/feed.njk"]
FEED --> META["src/_data/site.json"]
P --> PF["Pagefind indexing"]

Diagram sources

  • [package.json:5-12](file://package.json#L5-L12)
  • [.eleventy.js:216-261](file://.eleventy.js#L216-L261)
  • [src/feed.njk:1-27](file://src/feed.njk#L1-L27)
  • [src/_data/site.json:1-20](file://src/_data/site.json#L1-L20)

Section sources

  • [package.json:5-12](file://package.json#L5-L12)
  • [.eleventy.js:216-261](file://.eleventy.js#L216-L261)
  • [src/feed.njk:1-27](file://src/feed.njk#L1-L27)

Performance Considerations

  • Conditional transforms: Only enable heavy transforms (like minification) in production to keep development builds fast.
  • Watch targets: Limit watch scope to reduce rebuild cycles during development.
  • Passthrough copy: Avoid unnecessary copying of large binary blobs; consider processing images separately.
  • RSS generation: Keep the feed template minimal and avoid expensive computations inside loops.
  • Search indexing: Pagefind runs after Eleventy; ensure build scripts are ordered correctly.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Transform not applied
    • Verify the transform is registered and the output path ends with .html
    • Confirm environment variable gating for production-only transforms
  • RSS feed empty or outdated
    • Ensure the “news” collection is populated and sorted by date
    • Confirm the feed template permalink and collection usage
  • Build fails or slow
    • Review watch targets and passthrough copy configuration
    • Check for large assets being copied unnecessarily
  • Debugging tips
    • Use Eleventy’s built-in logging and filters for inspection
    • Temporarily disable minification to isolate issues

Section sources

  • [.eleventy.js:241-261](file://.eleventy.js#L241-L261)
  • [src/feed.njk:1-27](file://src/feed.njk#L1-L27)

Conclusion

The project leverages Eleventy’s transform system to enhance content and optimize output for production. Obsidian syntax processing improves content authoring ergonomics, while conditional HTML minification reduces payload sizes. RSS generation is cleanly separated from content rendering via a dedicated template that consumes the “news” collection. By integrating asset optimization and refining watch targets, the build can be further tuned for speed and reliability.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Adding a New Transform

Steps:

  • Register the transform in the Eleventy configuration
  • Gate production-only transforms behind environment checks
  • Target only HTML files when applicable
  • Keep transforms idempotent and fast

Example reference:

  • [Add transform registration:216-239](file://.eleventy.js#L216-L239)
  • [Production gating pattern:241-261](file://.eleventy.js#L241-L261)

Section sources

  • [.eleventy.js:216-261](file://.eleventy.js#L216-L261)

Optimizing Build Performance

  • Keep development builds lean by disabling heavy transforms
  • Narrow watch targets to relevant directories
  • Use passthrough copy judiciously for static assets
  • Integrate image processing and compression if needed

Section sources

  • [.eleventy.js:6-22](file://.eleventy.js#L6-L22)
  • [package.json:5-12](file://package.json#L5-L12)

Debugging Transform Issues

  • Inspect transformed output in the built site
  • Temporarily bypass transforms to isolate problems
  • Use Eleventy filters for quick data inspection
  • Validate environment variables for production-only transforms

Section sources

  • [.eleventy.js:241-261](file://.eleventy.js#L241-L261)

Caching Strategies and Build-Time Optimizations

  • Environment-based toggles: Apply heavy optimizations only in production
  • Static asset handling: Prefer processed assets over raw originals
  • Search integration: Pagefind indexing occurs after Eleventy; ensure correct script ordering

Section sources

  • [README.md:556-588](file://README.md#L556-L588)
  • [package.json:5-12](file://package.json#L5-L12)